feat: implement BalanceEmptyState component #21391

georgewrmarshall · 2025-10-18T00:50:58Z

Description

This PR implements the BalanceEmptyState component on the homepage when users have a zero balance across all mainnet networks. It is hidden behind the homepageRedesignV1Key feature flag which will be used for full page scroll of the homepage.

Shows BalanceEmptyState component for accounts with an aggregated balance of zero across mainnets(excludes testnets)
Applies to only AccountGroupBalance component.
Replaces the regular balance display with an empty state component when total aggregated balance is zero
Replaces previous TokenListFooter(Removed in this PR: chore: Remove TokenListFooter component in favor of balance empty state #21490)
Hidden behind the homepageRedesignV1Key feature flag
Adds new selectWalletBalanceForEmptyState to get balance across all networks
Adds e2e tests

Changelog

CHANGELOG entry: Updating zero balance display to "Add funds" card

Related issues

Fixes: https://consensyssoftware.atlassian.net/browse/DSYS-153

Manual testing steps

Feature: Balance Empty State on Homepage

  Background:
    Given the homepageRedesignV1Key feature flag is enabled

  Scenario: User with zero balance across all aggregated networks sees empty state
    Given user has a wallet with zero balance across all aggregated networks (Evm and nonEvm)
    When user navigates to the homepage
    Then user should see the BalanceEmptyState component with illustration and "Add funds" button
    And user should not see the regular balance display showing "$0.00"

  Scenario: User with positive balance on all aggregated networks sees positive balance
    Given user has a wallet with positive balance across aggregated networks (EVM and non EVM)
    When user navigates to the homepage
    Then user should see the normal balance display showing the actual dollar amount
    And user should not see the BalanceEmptyState component

  Scenario: User changes to network with empty balance sees zero balance
    Given user has positive balance on some networks but zero on others
    When user switches to a network where they have zero balance (EVM and non EVM)
    Then user should see "$0.00" balance display

  Scenario: User changes to network with positive balance sees positive balance (including test networks)
    Given user has zero balance on some networks but positive on others
    When user switches to a network where they have positive balance (mainnet, Sepolia, Goerli, etc.)
    Then user should see the normal balance display with actual amount
    And user should not see the BalanceEmptyState component
    And this behavior should be consistent across mainnet and test networks

  Scenario: User taps "Add funds" button from empty state
    Given user sees the BalanceEmptyState on homepage
    When user taps the "Add funds" button
    Then user should be navigated to the buy crypto page (not deposit flow)
    And appropriate analytics events should be tracked

  Scenario: Feature flag disabled - no empty state shown
    Given the homepageRedesignV1Key feature flag is disabled
    And user has zero balance
    When user navigates to the homepage
    Then user should see the regular "$0.00" balance display
    And user should not see the BalanceEmptyState component

  Scenario: Privacy mode interaction with empty state
    Given user has zero balance and sees BalanceEmptyState
    When user toggles privacy mode
    Then the BalanceEmptyState should remain visible (not affected by privacy toggle)

  Scenario: Loading states
    Given user navigates to homepage
    When balance data is still loading
    Then user should see skeleton/loader components
    And user should not see BalanceEmptyState or balance display until data loads

Screenshots/Recordings

Before

Empty balance showed a 0 balance and footer CTA to go to deposit

before720.mov

Loading balance on first import of an account with zero balance

loadingbefore720.mov

After

Empty balance now shows BalanceEmptyState component

after720.mov

The flicker between a zero balance(now empty state) still exists and is an architectural issue outside of the scope of this PR. This is being worked on by the @MetaMask/metamask-assets team

loadingafter720.mov

Pre-merge author checklist

I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
I've completed the PR template to the best of my ability
I've included tests if applicable
I've documented my code using JSDoc format if applicable
I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or recordings and or screenshots.

Note

Show BalanceEmptyState in AccountGroupBalance when aggregated mainnet balance is zero (feature-flagged), with new selector and comprehensive tests.

UI (Wallet):
- Display BalanceEmptyState in AccountGroupBalance when aggregated mainnet balance is zero; hide on testnets; keep skeleton while loading; gated by selectHomepageRedesignV1Enabled.
- Uses TEST_NETWORK_IDS and selectEvmChainId to suppress empty state on test networks.
Selectors:
- Add selectAccountGroupBalanceForEmptyState to compute selected group balance across mainnet networks only, using CAIP utilities and excluding TEST_NETWORK_IDS and NON_EVM_TESTNET_IDS.
Tests:
- Unit: update AccountGroupBalance.test.tsx to cover empty state rendering; add selector tests for network filtering, no selection, and missing group fallbacks.
- E2E: add balance-empty-state.spec.ts validating visibility on mainnet vs testnets, navigation to buy flow, and persistence after restart; extend page object WalletView and selectors with BALANCE_EMPTY_STATE_* IDs.

^{Written by Cursor Bugbot for commit 2078f33. This will update automatically on new commits. Configure here.}

github-actions · 2025-10-18T00:51:13Z

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

app/components/UI/Tokens/TokenList/index.tsx

codecov-commenter · 2025-10-24T19:23:39Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.09%. Comparing base (9c85997) to head (f1ac442).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #21391      +/-   ##
==========================================
+ Coverage   76.98%   77.09%   +0.11%     
==========================================
  Files        3715     3719       +4     
  Lines       93270    93446     +176     
  Branches    17894    17929      +35     
==========================================
+ Hits        71801    72046     +245     
+ Misses      16580    16508      -72     
- Partials     4889     4892       +3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

app/components/UI/Assets/components/Balance/AccountGroupBalance.test.tsx

Copilot

Pull Request Overview

This PR implements the BalanceEmptyState component on the homepage when users have a zero balance across all networks, replacing the default zero balance display with an engaging card featuring a "Fund your wallet" illustration and "Add funds" button to improve the onboarding experience for new users.

Key changes:

Integrated BalanceEmptyState into both PortfolioBalance (legacy multichain) and AccountGroupBalance (multichain accounts state 2) components
Replaced ButtonHero with standard Button component in BalanceEmptyState
Removed TokenListFooter from token list display

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
app/components/UI/Tokens/TokenList/index.tsx	Removed TokenListFooter component from list display
app/components/UI/Tokens/TokenList/PortfolioBalance/index.tsx	Integrated BalanceEmptyState for zero balance display
app/components/UI/Tokens/TokenList/PortfolioBalance/index.test.tsx	Added comprehensive test coverage for empty state scenarios
app/components/UI/BalanceEmptyState/BalanceEmptyState.tsx	Replaced ButtonHero with standard Button component
app/components/UI/Assets/components/Balance/AccountGroupBalance.tsx	Integrated BalanceEmptyState for zero balance display
app/components/UI/Assets/components/Balance/AccountGroupBalance.test.tsx	Added test coverage for empty state scenarios

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

app/components/UI/Tokens/TokenList/PortfolioBalance/index.test.tsx

app/components/UI/Assets/components/Balance/AccountGroupBalance.test.tsx

app/components/hooks/useMultichainBalances/useMultichainBalances.types.ts

georgewrmarshall · 2025-10-27T19:21:08Z

app/components/UI/Assets/components/Balance/AccountGroupBalance.tsx

+  const isHomepageRedesignV1Enabled = useSelector(
+    selectHomepageRedesignV1Enabled,
+  );


Using new feature flag to conditionally render the balance empty state

app/components/UI/BalanceEmptyState/BalanceEmptyState.tsx

app/components/UI/BalanceEmptyState/BalanceEmptyState.test.tsx

… balance

georgewrmarshall · 2025-10-31T05:07:43Z

app/components/UI/Assets/components/Balance/AccountGroupBalance.test.tsx

+  // This selector is used to display the BalanceEmptyState
+  selectAccountGroupBalanceForEmptyState: jest.fn(() => null),
+}));
+
+// Mock homepage redesign feature flag for BalanceEmptyState
+jest.mock('../../../../../selectors/featureFlagController/homepage', () => ({
+  selectHomepageRedesignV1Enabled: jest.fn(() => true),
+}));
+
+// This selector is used to determine if the current network is a testnet for BalanceEmptyState display logic
+jest.mock('../../../../../selectors/networkController', () => ({
+  ...jest.requireActual('../../../../../selectors/networkController'),
+  selectEvmChainId: jest.fn(() => '0x1'), // Ethereum mainnet (not a testnet)
+  selectChainId: jest.fn(() => '0x1'), // BalanceEmptyState also needs this
+}));
+
+// Mock navigation hooks used by BalanceEmptyState
+jest.mock('@react-navigation/native', () => ({
+  ...jest.requireActual('@react-navigation/native'),
+  useNavigation: () => ({
+    navigate: jest.fn(),
+    goBack: jest.fn(),
+    reset: jest.fn(),
+  }),
+}));
+
+// Mock metrics hook used by BalanceEmptyState
+jest.mock('../../../../../components/hooks/useMetrics', () => ({
+  useMetrics: () => ({
+    trackEvent: jest.fn(),
+    createEventBuilder: jest.fn(() => ({ record: jest.fn() })),
+  }),
 }));


Adding necessary mocks for BalanceEmptyState component

georgewrmarshall · 2025-10-31T05:08:06Z

app/components/UI/Assets/components/Balance/AccountGroupBalance.test.tsx

+  it('renders empty state when account group balance is zero', () => {
+    const {
+      selectAccountGroupBalanceForEmptyState,
+      selectBalanceBySelectedAccountGroup,
+    } = jest.requireMock('../../../../../selectors/assets/balances');
+
+    // Mock the regular balance selector to return data (prevents skeleton loader)
+    (selectBalanceBySelectedAccountGroup as jest.Mock).mockImplementation(
+      () => ({
+        totalBalanceInUserCurrency: 100, // Some non-zero amount for current network
+        userCurrency: 'usd',
+      }),
+    );
+
+    // Mock the empty state selector to return zero balance across all mainnet networks
+    (selectAccountGroupBalanceForEmptyState as jest.Mock).mockImplementation(
+      () => ({
+        totalBalanceInUserCurrency: 0, // Zero across all mainnet networks
+        userCurrency: 'usd',
+      }),
+    );
+
+    const { getByTestId } = renderWithProvider(<AccountGroupBalance />, {
+      state: testState,
+    });
+
+    const el = getByTestId(
+      WalletViewSelectorsIDs.BALANCE_EMPTY_STATE_CONTAINER,
+    );
+    expect(el).toBeOnTheScreen();
+  });


Adding test to check for balance emtpy state

georgewrmarshall · 2025-10-31T05:10:07Z

app/components/UI/Assets/components/Balance/AccountGroupBalance.tsx

+  selectAccountGroupBalanceForEmptyState,
 } from '../../../../../selectors/assets/balances';
+import { selectHomepageRedesignV1Enabled } from '../../../../../selectors/featureFlagController/homepage';
+import { selectEvmChainId } from '../../../../../selectors/networkController';
+import { TEST_NETWORK_IDS } from '../../../../../constants/network';


Importing new selector to calculate account group balance across all main nets, the feature flag for the new homepage redesign which includes full page scroll, the selector for current evm network and test networks ids for empty state display logic

georgewrmarshall · 2025-10-31T05:10:28Z

app/components/UI/Assets/components/Balance/AccountGroupBalance.tsx

 import { Skeleton } from '../../../../../component-library/components/Skeleton';
 import { useFormatters } from '../../../../hooks/useFormatters';
 import AccountGroupBalanceChange from '../../components/BalanceChange/AccountGroupBalanceChange';
+import BalanceEmptyState from '../../../BalanceEmptyState';


Importing BalanceEmptyState ui component

georgewrmarshall · 2025-10-31T05:10:49Z

app/components/UI/Assets/components/Balance/AccountGroupBalance.tsx

+  const accountGroupBalance = useSelector(
+    selectAccountGroupBalanceForEmptyState,
+  );


Getting account group balance across all chains using new selector

georgewrmarshall · 2025-10-31T05:13:11Z

app/components/UI/Assets/components/Balance/AccountGroupBalance.tsx

+  // Check if account group balance (across all mainnet networks) is zero for empty state
+  const hasZeroAccountGroupBalance =
+    accountGroupBalance && accountGroupBalance.totalBalanceInUserCurrency === 0;
+
+  // Check if current network is a testnet
+  const isCurrentNetworkTestnet = TEST_NETWORK_IDS.includes(selectedChainId);
+
+  // Show empty state on accounts with an aggregated mainnet balance of zero
+  const shouldShowEmptyState =
+    hasZeroAccountGroupBalance &&
+    isHomepageRedesignV1Enabled &&
+    !isCurrentNetworkTestnet;


Logic for displaying Balance empty state.

Show if the account group has a zero balance across all main nets and isHomepageRedesignV1Enabled feature flag is enabled

Do not show if it's a test network regardless of balance - show $0.00

georgewrmarshall · 2025-10-31T05:13:46Z

app/selectors/assets/balances.test.ts

    });
  });
+
+  describe('selectAccountGroupBalanceForEmptyState', () => {


Adding tests for new selector

georgewrmarshall · 2025-10-31T05:14:33Z

app/selectors/assets/balances.ts

+import { NON_EVM_TESTNET_IDS } from '@metamask/multichain-network-controller';
+import {
+  parseCaipChainId,
+  CaipChainId,
+  KnownCaipNamespace,
+} from '@metamask/utils';
+import { toHex } from '@metamask/controller-utils';
+import { TEST_NETWORK_IDS } from '../../constants/network';


Import helpful consts and utils for new selectAccountGroupBalanceForEmptyState selector

sonarqubecloud · 2025-10-31T05:29:47Z

Quality Gate passed

Issues
8 New issues
0 Accepted issues

Measures
0 Security Hotspots
98.3% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

cursor · 2025-10-31T05:36:58Z

app/components/UI/Assets/components/Balance/AccountGroupBalance.tsx

+    accountGroupBalance && accountGroupBalance.totalBalanceInUserCurrency === 0;
+
+  // Check if current network is a testnet
+  const isCurrentNetworkTestnet = TEST_NETWORK_IDS.includes(selectedChainId);


Bug: Bug

The testnet detection logic in AccountGroupBalance uses EVM-specific selectors (selectEvmChainId and TEST_NETWORK_IDS). This incorrectly identifies non-EVM testnets (e.g., Solana) as mainnet, causing the empty state to display instead of the numerical balance ($0.00).

We currently only show EVM test networks but this is a good point. If we were to add solana test net we may see the empty state. Do we have a non EVM test network constant that we can use here. Do you know @salimtb?

Copilot

Pull Request Overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

cortisiko

Looks good! 🌮 🌮

metamaskbot added the team-design-system All issues relating to design system in Mobile label Oct 18, 2025

github-actions bot added the size-L label Oct 18, 2025

georgewrmarshall changed the title ~~feat: Implement BalanceEmptyState component on homepage for zero balance users~~ feat: implement BalanceEmptyState component on homepage for zero balance users Oct 19, 2025

georgewrmarshall added needs-qa Any New Features that needs a full manual QA prior to being added to a release. Run E2E Smoke Test labels Oct 19, 2025

georgewrmarshall self-assigned this Oct 19, 2025

georgewrmarshall force-pushed the feat/balance-empty-state branch from 1403362 to 874da16 Compare October 21, 2025 19:26

github-actions bot added size-M and removed size-L labels Oct 21, 2025

georgewrmarshall mentioned this pull request Oct 21, 2025

chore: Remove TokenListFooter component in favor of balance empty state #21490

Merged

7 tasks

georgewrmarshall changed the title ~~feat: implement BalanceEmptyState component on homepage for zero balance users~~ feat: implement BalanceEmptyState component Oct 21, 2025

georgewrmarshall force-pushed the feat/balance-empty-state branch from 874da16 to 88f746b Compare October 21, 2025 23:34

georgewrmarshall commented Oct 21, 2025

View reviewed changes

app/components/UI/Tokens/TokenList/index.tsx Outdated Show resolved Hide resolved

georgewrmarshall force-pushed the feat/balance-empty-state branch 2 times, most recently from 51cc193 to 33d1845 Compare October 24, 2025 19:00

georgewrmarshall force-pushed the feat/balance-empty-state branch from f1ac442 to 175af1f Compare October 24, 2025 20:31

georgewrmarshall commented Oct 24, 2025

View reviewed changes

app/components/UI/Assets/components/Balance/AccountGroupBalance.test.tsx Show resolved Hide resolved

georgewrmarshall force-pushed the feat/balance-empty-state branch from 8080bee to b36ea70 Compare October 27, 2025 15:34

georgewrmarshall requested a review from Copilot October 27, 2025 17:33

Copilot AI reviewed Oct 27, 2025

View reviewed changes

app/components/UI/Tokens/TokenList/PortfolioBalance/index.test.tsx Outdated Show resolved Hide resolved

app/components/UI/Assets/components/Balance/AccountGroupBalance.test.tsx Outdated Show resolved Hide resolved

georgewrmarshall commented Oct 27, 2025

View reviewed changes

app/components/hooks/useMultichainBalances/useMultichainBalances.types.ts Show resolved Hide resolved

georgewrmarshall commented Oct 27, 2025

View reviewed changes

app/components/UI/BalanceEmptyState/BalanceEmptyState.tsx Show resolved Hide resolved

georgewrmarshall marked this pull request as ready for review October 27, 2025 19:56

georgewrmarshall requested review from a team as code owners October 27, 2025 19:56

georgewrmarshall force-pushed the feat/balance-empty-state branch from 172814e to d6a61a8 Compare October 27, 2025 21:01

georgewrmarshall commented Oct 27, 2025

View reviewed changes

app/components/UI/BalanceEmptyState/BalanceEmptyState.test.tsx Show resolved Hide resolved

georgewrmarshall added 4 commits October 30, 2025 22:06

chore: updating tests for account group balance with new selectors

637f4a8

chore: updating e2e tests to follow page object model

449a35f

chore: consolidating test selectors to wallet view

14c56ab

chore: refactoring selectors, adding tests and updating account group…

2078f33

… balance

georgewrmarshall force-pushed the feat/balance-empty-state branch from 4115e16 to 2078f33 Compare October 31, 2025 05:06

github-actions bot added size-L and removed size-M labels Oct 31, 2025

georgewrmarshall commented Oct 31, 2025

View reviewed changes

georgewrmarshall requested a review from Copilot October 31, 2025 05:33

georgewrmarshall marked this pull request as ready for review October 31, 2025 05:33

cursor bot reviewed Oct 31, 2025

View reviewed changes

Copilot AI reviewed Oct 31, 2025

View reviewed changes

cortisiko approved these changes Oct 31, 2025

View reviewed changes

georgewrmarshall added QA Passed QA testing has been completed and passed and removed needs-qa Any New Features that needs a full manual QA prior to being added to a release. labels Oct 31, 2025

salimtb approved these changes Oct 31, 2025

View reviewed changes

georgewrmarshall added this pull request to the merge queue Oct 31, 2025

Merged via the queue into main with commit 91c23b3 Oct 31, 2025
100 of 101 checks passed

georgewrmarshall deleted the feat/balance-empty-state branch October 31, 2025 15:59

github-actions bot locked and limited conversation to collaborators Oct 31, 2025

metamaskbot added the release-7.59.0 Issue or pull request that will be included in release 7.59.0 label Oct 31, 2025

Uh oh!

feat: implement BalanceEmptyState component #21391

feat: implement BalanceEmptyState component #21391

Conversation

georgewrmarshall commented Oct 18, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changelog

Related issues

Manual testing steps

Screenshots/Recordings

Before

After

Pre-merge author checklist

Pre-merge reviewer checklist

Uh oh!

github-actions bot commented Oct 18, 2025

Uh oh!

Uh oh!

codecov-commenter commented Oct 24, 2025

Codecov Report

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Oct 31, 2025

Quality Gate passed

Uh oh!

cursor bot Oct 31, 2025

Choose a reason for hiding this comment

Bug: Bug

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

cortisiko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

georgewrmarshall commented Oct 18, 2025 •

edited by cursor bot

Loading

georgewrmarshall Oct 31, 2025 •

edited

Loading